.\"	$OpenBSD: pkg_locate.1,v 1.2 2013/10/21 09:04:47 bentley Exp $
.\"
.\" Copyright (c) 2013 Robert Peichaer <rpe@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 21 2013 $
.Dt PKG_LOCATE 1
.Os
.Sh NAME
.Nm pkg_locate
.Nd find files in OpenBSD packages quickly
.Sh SYNOPSIS
.Nm pkg_locate
.Bk -words
.Op Fl bcimSs
.Op Fl l Ar limit
.Ar pattern ...
.Ek
.Sh DESCRIPTION
.Nm
searches a database of files for all pathnames which match the
specified pattern.
The options for
.Nm
are the same as for
.Xr locate 1 ,
which is used internally.
.Pp
There are two flavors of the pkglocatedb package:
installed as
.Pa pkglocatedb ,
providing a database with all files in
.Ox
packages; and
.Pa pkglocatedb-src ,
providing the same database including all installation set files.
.Pp
The search result for
.Ox
package files has the following format:
.Pp
.Dl fullpkgname:pkgpath:pathname
.Pp
where
.Ar fullpkgname
is the name of the package (see
.Xr bsd.port.mk 5 )
without the trailing .tgz,
.Ar pkgpath
is the location within the ports tree (see
.Xr pkgpath 7 )
and
.Ar pathname
is the absoute pathname of the installed file.
.Pp
The search result for base system and X Window System files has the
following format:
.Pp
.Dl srcdir/setname:setfilename:pathname
.Pp
where
.Ar srcdir
is
.Qq src
for base system or
.Qq xenocara
for X Window System,
.Ar setname
is the name of the install set,
.Ar setfilename
is the name of the install set file including the release version
without the .tgz suffix, and
.Ar pathname
is the absoute pathname of the installed file.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl b
For each entry in the database, perform the search on the last
component of path.
.It Fl c
Suppress normal output; instead print a count of matching file names.
.It Fl i
Ignore case distinctions in both the pattern and the database.
.It Fl l Ar limit
Limit output to a specific number of files and exit.
.It Fl m
Use
.Xr mmap 2
instead of the
.Xr stdio 3
library.
This is the default behavior.
It performs better in most cases.
.It Fl S
Print some statistics about the database and exit.
.It Fl s
Use the
.Xr stdio 3
library instead of
.Xr mmap 2 .
.El
.Sh FILES
.Bl -tag -compact -width /usr/local/share/pkglocatedb
.It /usr/local/share/pkglocatedb
locate database containing information about files in
.Ox
packages and optionally in the
.Ox
installation sets.
.El
.Sh SEE ALSO
.Xr locate 1 ,
.Xr bsd.port.mk 5 ,
.Xr pkgpath 7
.Sh AUTHORS
.An Marc Espie Aq Mt espie@openbsd.org
